from .typedef import *

class ReadInterface(ABC):
    """
    数据读取接口抽象基类，定义了统一的数据读取操作规范。

    该类是一个抽象基类，用于定义数据读取的基本接口和规范。具体的读取实现需要继承该类并实现其抽象方法。

    方法:
        read: 严格类型定义的数据读取接口，支持多种读取格式和配置选项。
        read_single: 读取单个地址值对的专用接口，提供针对单值读取的简化参数结构。
        read_batch: 批量读取多个地址值对的专用接口，提供针对批量读取的优化参数结构。
        read_config: 通过配置字典进行读取的专用接口，提供针对配置读取的优化参数结构。

    注意:
        所有方法均为抽象方法，具体实现需要由子类完成。
    """

    @abstractmethod
    def read(self,
             address: FullReadType,
             *args: Union[
                 int,              # timeout (seconds)
                 float,            # timeout (seconds)
                 str,              # data_type or read_option
                 DataType,         # data type enum
                 ReadOption,       # read option enum
                 PreReaderType,    # pre-read processor function
                 PostReaderType,   # post-read processor function
                 Dict[str, Any]    # additional configuration
             ],
             timeout: Optional[Union[int, float]] = None,
             data_type: Optional[Union[str, DataType]] = None,
             sync: Optional[bool] = None,
             retry: Optional[int] = None,
             raise_on_error: Optional[bool] = None,
             quality_check: Optional[bool] = None,
             prereaders: Optional[List[PreReaderType]] = None,
             postreaders: Optional[List[PostReaderType]] = None,
             batch_size: Optional[int] = None,
             **kwargs: Any) -> Union[
                 Any,                     # single read result
                 List[Any],               # batch read results as list
                 Dict[AddressType, Any],  # batch read results as dict
                 Dict[str, Any]           # config read results
             ]:
        """
        严格类型定义的数据读取接口，支持多种读取格式和配置选项。

        该方法提供了一个统一的接口来从不同的地址读取各种类型的数据，支持单个读取、批量读取和配置读取等多种模式。
        可以通过位置参数、关键字参数或配置字典来指定读取参数，具有灵活的参数解析和配置合并机制。

        Args:
            address (FullReadType): 读取地址，支持以下几种类型：
                - AddressType: 单个地址，如 "address1" 或 100
                - List[AddressType]: 地址列表，如 ["address1", "address2"]
                - Tuple[AddressType, str]: 带数据类型的地址，如 ("address1", "int")
                - Tuple[AddressType, str, int]: 带数据类型和长度的地址，如 ("address1", "string", 4)
                - Tuple[AddressType, str, str]: 带数据类型和选项的地址，如 ("address1", "int", "option1")
                - List[Tuple[AddressType, str]]: 带数据类型的地址列表，如 [("address1", "int"), ("address2", "float")]
                - List[Tuple[AddressType, str, int]]: 带数据类型和长度的地址列表，如 [("address1", "string", 4), ("address2", "string", 4)]
                - List[Tuple[AddressType, str, str]]: 带数据类型和选项的地址列表，如 [("address1", "int", "option1"), ("address2", "float", "option2")]
                - Dict[str, Any]: 带配置的读取，支持以下格式：
                    - {"address": "address1", "data_type": "int"}: 单个地址配置读取
                    - {"addresses": ["address1", "address2"], "data_type": "int"}: 批量地址配置读取，数据类型一致
                    - {"addresses": ["address1", "address2"], "data_types": ["int", "float"]}: 批量地址配置读取，数据类型不一致
                    - {"address": "address1", "data_type": "int", "length": 4}: 带额外参数的配置读取

        Positional Args:
            *args: 位置参数，支持以下类型：
                - int/float: 超时时间（秒），用于指定单次读取操作的最大等待时间
                - str: 数据类型标识符，支持DataType枚举的字符串值（如'int', 'float'等）或读取选项标识符（如'sync', 'async'）
                - DataType: 枚举类型参数，明确指定读取数据的类型，包含丰富类型支持如：
                            INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE, STRING等
                - ReadOption: 枚举类型参数，指定读取操作模式，包含SYNC（同步）和ASYNC（异步）模式
                - Callable: 可调用对象，用于数据预处理和后处理。无参数或单参数函数被识别为prereader，
                           多参数函数被识别为postreader
                - Dict[str, Any]: 额外配置参数，将直接合并到最终配置字典中
                - 其他类型参数将被忽略
        Keyword Args:
            以下关键字参数提供了更明确的配置方式，优先级高于*args中的参数：

            timeout (Optional[Union[int, float]], optional): 单次读取操作的最大等待时间（秒），默认None表示使用系统默认超时时间
                如果在指定时间内操作未完成，将引发超时异常（如果raise_on_error=True）
            data_type (Optional[Union[str, DataType]], optional): 指定读取数据的类型，支持字符串或DataType枚举。
                默认为None，表示自动推断数据类型。常用类型包括'int', 'float', 'string', 'bool'等
            sync (Optional[bool], optional): 同步读取标志，指定读取操作是同步还是异步执行，默认None表示使用系统默认设置
                True表示同步读取，False表示异步读取
            retry (Optional[int], optional): 读取失败时的重试次数，默认None表示使用系统默认重试次数
                0表示不重试，仅执行一次读取操作
            raise_on_error (Optional[bool], optional): 错误处理标志，指定读取失败时是否抛出异常，默认None表示使用系统默认设置
                True表示抛出异常，False表示返回默认值或None
            quality_check (Optional[bool], optional): 数据质量检查标志，指定是否在读取后进行数据质量检查，默认None表示使用系统默认设置
                True表示进行质量检查，False表示跳过质量检查
            prereaders (Optional[List[PreReaderType]], optional): 读取前处理函数列表。
                这些函数将在数据读取前依次执行，用于准备读取操作
            postreaders (Optional[List[PostReaderType]], optional): 读取后处理函数列表。
                这些函数将在数据读取后依次执行，用于处理读取结果
            batch_size (Optional[int], optional): 批量读取分块大小，指定批量读取时每个分块的大小。
                None表示不分块处理，默认值依赖于具体实现

            **kwargs: 其他关键字参数，将被合并到配置中，支持所有在args中提到的参数类型，
                以及额外的协议特定参数。这些参数将覆盖通过*args解析的参数

        Returns:
            Union[Any, List[Any], Dict[AddressType, Any], Dict[str, Any]]: 读取结果，根据输入参数类型返回不同格式：
                - Any: 单个读取操作的结果，返回读取到的值
                - List[Any]: 批量读取操作的结果列表，按地址顺序返回读取值
                - Dict[AddressType, Any]: 批量读取操作的结果映射，键为地址，值为读取结果
                - Dict[str, Any]: 配置读取操作的结果，可能包含额外的元信息

        Raises:
            TypeError: 当传入不支持的地址格式时，或者参数类型不匹配时抛出
            ValueError: 当质量检查失败时（如果启用了quality_check），或者参数值无效时抛出
            Exception: 当读取过程中发生错误且raise_on_error=True时抛出

        Examples:
            # 单个读取：最简单的读取形式
            value = client.read("address1")

            # 带数据类型的单个读取：显式指定数据类型
            value = client.read(("address1", "int"))

            # 使用位置参数指定数据类型
            value = client.read("address1", "int")

            # 批量读取：通过列表一次读取多个地址
            values = client.read(["address1", "address2"])

            # 带配置的批量读取：通过元组列表指定多个地址和数据类型
            values = client.read([("address1", "int"), ("address2", "float")])

            # 带数据类型和选项的批量读取
            values = client.read([("address1", "int", "option1"), ("address2", "float", "option2")])

            # 使用关键字参数配置：通过关键字参数指定额外配置
            values = client.read("address1", timeout=10, data_type="int", sync=True)

            # 配置读取：通过配置字典执行读取操作
            result = client.read({
                "addresses": ["address1", "address2"],
                "data_type": "int"
            })

            # 带有所有可选参数的完整读取
            result = client.read(
                "address1",
                timeout=30,
                data_type=DataType.INT32,
                sync=True,
                retry=3,
                raise_on_error=True,
                quality_check=True
            )

        Note:
            1. 参数优先级：kwargs > args > defaults
            2. 支持的数据类型包括所有DataType枚举值
            3. 读取选项包括SYNC, ASYNC
            4. 当batch_size参数设置且读取数据量超过该值时，将自动分块处理
            5. prereaders在数据读取前执行，postreaders在数据读取后执行
        """
        pass

    @abstractmethod
    def read_single(self,
                    address: AddressType,
                    *args: Union[
                        int,              # timeout (seconds)
                        float,            # timeout (seconds)
                        str,              # data_type or read_option
                        DataType,         # data type enum
                        ReadOption,       # read option enum
                        PreReaderType,    # pre-read processor function
                        PostReaderType,   # post-read processor function
                        Dict[str, Any]    # additional configuration
                    ],
                    timeout: Optional[Union[int, float]] = None,
                    data_type: Optional[Union[str, DataType]] = None,
                    sync: Optional[bool] = None,
                    retry: Optional[int] = None,
                    raise_on_error: Optional[bool] = None,
                    quality_check: Optional[bool] = None,
                    prereaders: Optional[List[PreReaderType]] = None,
                    postreaders: Optional[List[PostReaderType]] = None,
                    **kwargs: Any) -> Any:
        """
        读取单个地址的专用接口，提供针对单值读取的简化参数结构。

        Args:
            address (AddressType): 读取地址，支持字符串或数字类型地址，如 "address1" 或 100

        Positional Args:
            *args: 位置参数，支持以下类型：
                - int/float: 超时时间（秒），用于指定单次读取操作的最大等待时间
                - str: 数据类型标识符，支持DataType枚举的字符串值（如'int', 'float'等）或读取选项标识符（如'sync', 'async'）
                - DataType: 枚举类型参数，明确指定读取数据的类型，包含丰富类型支持如：
                            INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE, STRING等
                - ReadOption: 枚举类型参数，指定读取操作模式，包含SYNC（同步）和ASYNC（异步）模式
                - Callable: 可调用对象，用于数据预处理和后处理。无参数或单参数函数被识别为prereader，
                           多参数函数被识别为postreader
                - Dict[str, Any]: 额外配置参数，将直接合并到最终配置字典中
                - 其他类型参数将被忽略
        Keyword Args:
            以下关键字参数提供了更明确的配置方式，优先级高于*args中的参数：

            timeout (Optional[Union[int, float]], optional): 单次读取操作的最大等待时间（秒），默认None表示使用系统默认超时时间
                如果在指定时间内操作未完成，将引发超时异常（如果raise_on_error=True）
            data_type (Optional[Union[str, DataType]], optional): 指定读取数据的类型，支持字符串或DataType枚举。
                默认为None，表示自动推断数据类型。常用类型包括'int', 'float', 'string', 'bool'等
            sync (Optional[bool], optional): 同步读取标志，指定读取操作是同步还是异步执行，默认None表示使用系统默认设置
                True表示同步读取，False表示异步读取
            retry (Optional[int], optional): 读取失败时的重试次数，默认None表示使用系统默认重试次数
                0表示不重试，仅执行一次读取操作
            raise_on_error (Optional[bool], optional): 错误处理标志，指定读取失败时是否抛出异常，默认None表示使用系统默认设置
                True表示抛出异常，False表示返回默认值或None
            quality_check (Optional[bool], optional): 数据质量检查标志，指定是否在读取后进行数据质量检查，默认None表示使用系统默认设置
                True表示进行质量检查，False表示跳过质量检查
            prereaders (Optional[List[PreReaderType]], optional): 读取前处理函数列表。
                这些函数将在数据读取前依次执行，用于准备读取操作
            postreaders (Optional[List[PostReaderType]], optional): 读取后处理函数列表。
                这些函数将在数据读取后依次执行，用于处理读取结果

            **kwargs: 其他关键字参数，将被合并到配置中，支持所有在args中提到的参数类型，
                以及额外的协议特定参数。这些参数将覆盖通过*args解析的参数

        Returns:
            Any: 单个读取操作的结果，返回读取到的值

        Raises:
            TypeError: 当传入不支持的地址格式时，或者参数类型不匹配时抛出
            ValueError: 当质量检查失败时（如果启用了quality_check），或者参数值无效时抛出
            Exception: 当读取过程中发生错误且raise_on_error=True时抛出

        Examples:
            # 最简单的单值读取
            value = client.read_single("address1")

            # 带数据类型的单值读取
            value = client.read_single("address1", "int")

            # 使用关键字参数配置
            value = client.read_single("address1", timeout=10, data_type="int", sync=True)

            # 带有所有可选参数的完整读取
            value = client.read_single(
                "address1",
                timeout=30,
                data_type=DataType.INT32,
                sync=True,
                retry=3,
                raise_on_error=True,
                quality_check=True
            )

        Note:
            1. 参数优先级：kwargs > args > defaults
            2. 支持的数据类型包括所有DataType枚举值
            3. 读取选项包括SYNC, ASYNC
            4. prereaders在数据读取前执行，postreaders在数据读取后执行
        """
        pass

    @abstractmethod
    def read_batch(self,
                   addresses: List[AddressType],
                   *args: Union[
                       int,              # timeout (seconds)
                       float,            # timeout (seconds)
                       str,              # data_type or read_option
                       DataType,         # data type enum
                       ReadOption,       # read option enum
                       PreReaderType,    # pre-read processor function
                       PostReaderType,   # post-read processor function
                       Dict[str, Any]    # additional configuration
                   ],
                   data_types: Optional[List[Union[str, DataType]]] = None,
                   timeout: Optional[Union[int, float]] = None,
                   sync: Optional[bool] = None,
                   retry: Optional[int] = None,
                   raise_on_error: Optional[bool] = None,
                   quality_check: Optional[bool] = None,
                   prereaders: Optional[List[PreReaderType]] = None,
                   postreaders: Optional[List[PostReaderType]] = None,
                   batch_size: Optional[int] = None,
                   **kwargs: Any) -> Union[
                       List[Any],               # batch read results as list
                       Dict[AddressType, Any]   # batch read results as dict
                   ]:
        """
        批量读取多个地址的专用接口，提供针对批量读取的优化参数结构。

        Args:
            addresses (List[AddressType]): 读取地址列表，支持字符串或数字类型地址，如 ["address1", "address2"] 或 [100, 200]
            data_types (Optional[List[Union[str, DataType]]], optional): 指定读取数据的类型列表，支持字符串或DataType枚举列表。
                默认为None，表示自动推断数据类型。常用类型包括'int', 'float', 'string', 'bool'等

        Positional Args:
            *args: 位置参数，支持以下类型：
                - int/float: 超时时间（秒），用于指定单次读取操作的最大等待时间
                - str: 数据类型标识符，支持DataType枚举的字符串值（如'int', 'float'等）或读取选项标识符（如'sync', 'async'）
                - DataType: 枚举类型参数，明确指定读取数据的类型，包含丰富类型支持如：
                            INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE, STRING等
                - ReadOption: 枚举类型参数，指定读取操作模式，包含SYNC（同步）和ASYNC（异步）模式
                - Callable: 可调用对象，用于数据预处理和后处理。无参数或单参数函数被识别为prereader，
                           多参数函数被识别为postreader
                - Dict[str, Any]: 额外配置参数，将直接合并到最终配置字典中
                - 其他类型参数将被忽略

        Keyword Args:
            以下关键字参数提供了更明确的配置方式，优先级高于*args中的参数：

            data_types (Optional[List[Union[str, DataType]]], optional): 指定读取数据的类型列表，支持字符串或DataType枚举列表。
                默认为None，表示自动推断数据类型。常用类型包括'int', 'float', 'string', 'bool'等
            timeout (Optional[Union[int, float]], optional): 单次读取操作的最大等待时间（秒），默认None表示使用系统默认超时时间
                如果在指定时间内操作未完成，将引发超时异常（如果raise_on_error=True）
            sync (Optional[bool], optional): 同步读取标志，指定读取操作是同步还是异步执行，默认None表示使用系统默认设置
                True表示同步读取，False表示异步读取
            retry (Optional[int], optional): 读取失败时的重试次数，默认None表示使用系统默认重试次数
                0表示不重试，仅执行一次读取操作
            raise_on_error (Optional[bool], optional): 错误处理标志，指定读取失败时是否抛出异常，默认None表示使用系统默认设置
                True表示抛出异常，False表示返回默认值或None
            quality_check (Optional[bool], optional): 数据质量检查标志，指定是否在读取后进行数据质量检查，默认None表示使用系统默认设置
                True表示进行质量检查，False表示跳过质量检查
            prereaders (Optional[List[PreReaderType]], optional): 读取前处理函数列表。
                这些函数将在数据读取前依次执行，用于准备读取操作
            postreaders (Optional[List[PostReaderType]], optional): 读取后处理函数列表。
                这些函数将在数据读取后依次执行，用于处理读取结果
            batch_size (Optional[int], optional): 批量读取分块大小，指定批量读取时每个分块的大小。
                None表示不分块处理，默认值依赖于具体实现

            **kwargs: 其他关键字参数，将被合并到配置中，支持所有在args中提到的参数类型，
                以及额外的协议特定参数。这些参数将覆盖通过*args解析的参数

        Returns:
            Union[List[Any], Dict[AddressType, Any]]: 批量读取操作的结果，根据输入参数类型返回不同格式：
                - List[Any]: 批量读取操作的结果列表，按地址顺序返回读取值
                - Dict[AddressType, Any]: 批量读取操作的结果映射，键为地址，值为读取结果

        Raises:
            TypeError: 当传入不支持的地址格式时，或者参数类型不匹配时抛出
            ValueError: 当质量检查失败时（如果启用了quality_check），或者参数值无效时抛出
            Exception: 当读取过程中发生错误且raise_on_error=True时抛出

        Examples:
            # 最简单的批量读取
            values = client.read_batch(["address1", "address2"])

            # 带数据类型的批量读取（所有数据类型一致）
            values = client.read_batch(["address1", "address2"], data_types="int")

            # 带数据类型列表的批量读取（数据类型不一致）
            values = client.read_batch(["address1", "address2"], data_types=["int", "float"])

            # 使用关键字参数配置
            values = client.read_batch(["address1", "address2"], timeout=10, data_types="int", sync=True)

            # 带有所有可选参数的完整读取
            values = client.read_batch(
                ["address1", "address2"],
                timeout=30,
                data_types=[DataType.INT32, DataType.FLOAT],
                sync=True,
                retry=3,
                raise_on_error=True,
                quality_check=True
            )

        Note:
            1. 参数优先级：kwargs > args > defaults
            2. 支持的数据类型包括所有DataType枚举值
            3. 读取选项包括SYNC, ASYNC
            4. 当batch_size参数设置且读取数据量超过该值时，将自动分块处理
            5. prereaders在数据读取前执行，postreaders在数据读取后执行
        """
        pass

    @abstractmethod
    def read_config(self,
                    config: Dict[str, Any],
                    *args: Union[
                        int,              # timeout (seconds)
                        float,            # timeout (seconds)
                        str,              # data_type or read_option
                        DataType,         # data type enum
                        ReadOption,       # read option enum
                        PreReaderType,    # pre-read processor function
                        PostReaderType,   # post-read processor function
                        Dict[str, Any]    # additional configuration
                    ],
                    timeout: Optional[Union[int, float]] = None,
                    data_type: Optional[Union[str, DataType]] = None,
                    sync: Optional[bool] = None,
                    retry: Optional[int] = None,
                    raise_on_error: Optional[bool] = None,
                    quality_check: Optional[bool] = None,
                    prereaders: Optional[List[PreReaderType]] = None,
                    postreaders: Optional[List[PostReaderType]] = None,
                    batch_size: Optional[int] = None,
                    **kwargs: Any) -> Dict[str, Any]:
        """
        通过配置字典进行读取的专用接口，提供针对配置读取的优化参数结构。

        Args:
            config (Dict[str, Any]): 读取配置字典，支持以下格式：
                - {"address": "address1", "data_type": "int"}: 单个地址配置读取
                - {"addresses": ["address1", "address2"], "data_type": "int"}: 批量地址配置读取，数据类型一致
                - {"addresses": ["address1", "address2"], "data_types": ["int", "float"]}: 批量地址配置读取，数据类型不一致
                - {"address": "address1", "data_type": "int", "length": 4}: 带额外参数的配置读取

        Positional Args:
            *args: 位置参数，支持以下类型：
                - int/float: 超时时间（秒），用于指定单次读取操作的最大等待时间
                - str: 数据类型标识符，支持DataType枚举的字符串值（如'int', 'float'等）或读取选项标识符（如'sync', 'async'）
                - DataType: 枚举类型参数，明确指定读取数据的类型，包含丰富类型支持如：
                            INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE, STRING等
                - ReadOption: 枚举类型参数，指定读取操作模式，包含SYNC（同步）和ASYNC（异步）模式
                - Callable: 可调用对象，用于数据预处理和后处理。无参数或单参数函数被识别为prereader，
                           多参数函数被识别为postreader
                - Dict[str, Any]: 额外配置参数，将直接合并到最终配置字典中
                - 其他类型参数将被忽略

        Keyword Args:
            以下关键字参数提供了更明确的配置方式，优先级高于*args中的参数：

            timeout (Optional[Union[int, float]], optional): 单次读取操作的最大等待时间（秒），默认None表示使用系统默认超时时间
                如果在指定时间内操作未完成，将引发超时异常（如果raise_on_error=True）
            data_type (Optional[Union[str, DataType]], optional): 指定读取数据的类型，支持字符串或DataType枚举。
                默认为None，表示自动推断数据类型。常用类型包括'int', 'float', 'string', 'bool'等
            sync (Optional[bool], optional): 同步读取标志，指定读取操作是同步还是异步执行，默认None表示使用系统默认设置
                True表示同步读取，False表示异步读取
            retry (Optional[int], optional): 读取失败时的重试次数，默认None表示使用系统默认重试次数
                0表示不重试，仅执行一次读取操作
            raise_on_error (Optional[bool], optional): 错误处理标志，指定读取失败时是否抛出异常，默认None表示使用系统默认设置
                True表示抛出异常，False表示返回默认值或None
            quality_check (Optional[bool], optional): 数据质量检查标志，指定是否在读取后进行数据质量检查，默认None表示使用系统默认设置
                True表示进行质量检查，False表示跳过质量检查
            prereaders (Optional[List[PreReaderType]], optional): 读取前处理函数列表。
                这些函数将在数据读取前依次执行，用于准备读取操作
            postreaders (Optional[List[PostReaderType]], optional): 读取后处理函数列表。
                这些函数将在数据读取后依次执行，用于处理读取结果
            batch_size (Optional[int], optional): 批量读取分块大小，指定批量读取时每个分块的大小。
                None表示不分块处理，默认值依赖于具体实现

            **kwargs: 其他关键字参数，将被合并到配置中，支持所有在args中提到的参数类型，
                以及额外的协议特定参数。这些参数将覆盖通过*args解析的参数

        Returns:
            Dict[str, Any]: 配置读取操作的结果，可能包含额外的元信息

        Raises:
            TypeError: 当传入不支持的地址格式时，或者参数类型不匹配时抛出
            ValueError: 当质量检查失败时（如果启用了quality_check），或者参数值无效时抛出
            Exception: 当读取过程中发生错误且raise_on_error=True时抛出

        Examples:
            # 单个地址配置读取
            result = client.read_config({"address": "address1", "data_type": "int"})

            # 批量地址配置读取
            result = client.read_config({"addresses": ["address1", "address2"], "data_type": "int"})

            # 带数据类型列表的批量地址配置读取
            result = client.read_config({"addresses": ["address1", "address2"], "data_types": ["int", "float"]})

            # 使用关键字参数配置
            result = client.read_config(
                {"addresses": ["address1", "address2"], "data_type": "int"},
                timeout=10,
                sync=True
            )

            # 带有所有可选参数的完整读取
            result = client.read_config(
                {"addresses": ["address1", "address2"], "data_type": "int"},
                timeout=30,
                data_type=DataType.INT32,
                sync=True,
                retry=3,
                raise_on_error=True,
                quality_check=True
            )

        Note:
            1. 参数优先级：kwargs > args > defaults
            2. 支持的数据类型包括所有DataType枚举值
            3. 读取选项包括SYNC, ASYNC
            4. 当batch_size参数设置且读取数据量超过该值时，将自动分块处理
            5. prereaders在数据读取前执行，postreaders在数据读取后执行
        """
        pass